Skip to content

Detect nullable in OpenAPI 3.1 documents (NullableDeprecation rule)#193

Merged
geemus merged 2 commits into
ota42y:masterfrom
takayamaki:pr5-nullable-deprecation
Jul 1, 2026
Merged

Detect nullable in OpenAPI 3.1 documents (NullableDeprecation rule)#193
geemus merged 2 commits into
ota42y:masterfrom
takayamaki:pr5-nullable-deprecation

Conversation

@takayamaki

@takayamaki takayamaki commented Jun 21, 2026

Copy link
Copy Markdown
Contributor

ref: #152

Continuing the OpenAPI 3.1 work from #192.

This PR adds a new SpecValidator rule:

  • OpenAPIParser::SpecValidator::Rules::NullableDeprecation

Design

In 3.0, nullable: true marks a schema as accepting null.
3.1 removed the keyword entirely in favor of type: [..., "null"].

The rule flags the mere presence of nullable on a 3.1 document — true and false are both violations, since the field itself is gone.
This matches how OAS treats removed keywords: it is not about the value, it is about the keyword being there at all.

# 3.1 document
schema:
  type: string
  nullable: false   # flagged — keyword removed in 3.1, even though false is the safe value

Implementation details

Detection inspects raw_schema directly

schema.nullable returns false when the key is absent and when it is explicitly set to false. The rule needs to distinguish those two states,
so it checks schema.raw_schema.key?('nullable') instead of the accessor:

each_schema(root) do |schema|
  next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('nullable')
  violations << violation(path: schema.object_reference, message: ...)
end

Wiring

One line added to the rules array in SpecValidator, plus the rule file under spec_validator/rules/. No changes to the parse layer or runtime
— parsing continues to accept nullable on either version; only the validator reports it.

Tests

  • Unit specs cover: 3.0 with nullable: true / false (clean), 3.1 with nullable: true / false (both flagged), 3.1 without nullable
    (clean), :unknown version (skipped).
  • Integration spec exercises the warn/raise dispatch path with openapi_3_1/nullable_30.yaml and nullable_31.yaml fixtures.

Spec_validator only. `nullable` is removed in 3.1; any presence on
a 3.1 document is flagged, regardless of true/false. Detection
inspects raw_schema directly so a literal `nullable: false` is not
confused with the field being absent.
`nullable` on a 3.1 document warns and raises (removed in favour of
type: [..., null]); the same keyword on a 3.0 document stays clean.
@takayamaki takayamaki marked this pull request as ready for review June 21, 2026 14:01

@geemus geemus left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm, thanks!

@geemus geemus merged commit b4a7d7d into ota42y:master Jul 1, 2026
14 checks passed
takayamaki added a commit to takayamaki/openapi_parser that referenced this pull request Jul 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants